Release 10.1A: OpenEdge Development:
Programming Interfaces

Generating encryption keys

The Progress 4GL provides a set of built-in key generation functions for quickly and effectively generating keys for symmetric encryption of the right size and content for a given algorithm. You can also use these functions to generate keys for any other encryption task, such as for use in generating message digests (see the "Using message digests in the 4GL" section). Using these functions you can generate two basic types of keys:

Random keys.
Password-based encryption (PBE) keys.

The strength of a cryptographic key depends on its randomness. The 4GL supports these key generation functions using specially tailored random number generators. For symmetric encryption itself as well as for the generation of PBE keys used in encryption, you can increase the effective key randomness by using an additional key value for both encryption and PBE key generation:

For symmetric encryption, the 4GL provides the option of combining an initialization vector (SECURITY-POLICY:SYMMETRIC-ENCRYPTION-IV attribute) with the symmetric key (SECURITY-POLICY:SYMMETRIC-ENCRYPTION-KEY attribute) to perform data encryption. By combining it with the symmetric key, an initialization vector increases effective key randomness, and therefore increases the strength of the encryption.
For generating PBE keys used in symmetric encryption, the 4GL provides the option of combining the user-supplied password with a salt that you can set as the value of the SECURITY-POLICY:ENCRYPTION-SALT attribute. A salt is an especially useful random value for generating PBE keys because passwords are typically very simple and often duplicated. A random salt ensures that the PBE key generated for a given password is always unique for each use of the same password.

Thus, the 4GL key generation functions allow you to generate symmetric encryption results whose randomness can be compounded and tailored for the algorithms that you have initialized for the SECURITY-POLICY system handle, as shown in Table 2–13.

Table 2–13: Cryptographic key generation functions

4GL function	Description
GENERATE-PBE-KEY(   password   [, salt] )	Evaluates to a RAW password-based key value with the number of bytes determined by the setting of the SECURITY-POLICY:SYMMETRIC-ENCRYPTION-ALGORITHM attribute. This function uses the PKCS#5/RFC 2898 standard for generating a symmetric encryption key based on the one-way hashing algorithm specified by SECURITY-POLICY:PBE-HASH-ALGORITHM. You can use this function to set one or both of these SECURITY-POLICY handle attributes with a value based on a password: SYMMETRIC-ENCRYPTION-KEY SYMMETRIC-ENCRYPTION-IV You must specify a character string-based value other than the Unknown value (?) for password, and you must maintain the same code page in order to use this function to recover the same key value using this password. Specify an 8-byte RAW value for salt in order to help ensure that the PBE key generated using password is unique for all other uses of the same password value. To obtain a random value for salt that is most likely to yield a unique PBE key, you can use the GENERATE-PBE-SALT function to generate the value. If you do not specify the salt option, the function uses any salt value (other than the Unknown value (?)) that you have set for the ENCRYPTION-SALT attribute of the SECURITY-POLICY handle. Note: You can use this function to set the SYMMETRIC-ENCRYPTION-KEY attribute directly as long as the same SYMMETRIC-ENCRYPTION-ALGORITHM setting, PBE-HASH-ALGORITHM setting, password, salt value, and code page are used to generate the PBE key value for both encryption and decryption.
GENERATE-PBE-SALT	Evaluates to a RAW random 8-byte value according to the setting of the SECURITY-POLICY:PBE-HASH-ALGORITHM attribute. You can use this function to set one or both of these values: The ENCRYPTION-SALT attribute of the SECURITY-POLICY handle. The salt parameter of the GENERATE-PBE-KEY function. Note: Be careful when using this function to directly set the salt parameter of the GENERATE-PBE-KEY function. If you do not save the generated PBE key value separately, but use it directly for encryption, this results in a nonrecoverable key value, rendering the encrypted data unusable. For the PBE key to be recoverable, you must be able to recover both the salt and the password that you combined to initially generate the key value. For more information, see the "Implementing symmetric cryptography in the 4GL" section.
GENERATE-RANDOM-KEY	Evaluates to a RAW random key value calculated by a pseudo random number generator (PRNG) and containing the number of bytes determined by the setting of the SECURITY-POLICY:SYMMETRIC-ENCRYPTION-ALGORITHM attribute. You can use this function to set one or both of these SECURITY-POLICY handle attributes with a random value: SYMMETRIC-ENCRYPTION-KEY SYMMETRIC-ENCRYPTION-IV Note: Do not use this function to directly set the SYMMETRIC-ENCRYPTION-KEY attribute. Because this attribute is not readable, setting it directly from this function leads to a nonrecoverable key value, rendering the encrypted data unusable.

Caution: You must ensure that all values and system conditions required to generate a symmetric key value are available to generate the cryptographic keys used for both encryption and decryption of the same data. Otherwise, encrypted data can become undecipherable and effectively lost.

For more information on symmetric keys and their generation, see OpenEdge Getting Started: Core Business Services .

Note: The 4GL also supports the encryption of keys especially for use in auditing, for example, to secure message authentication code (MAC) keys used to seal audit data for audit archiving. For more information on MACs, see the "Using message digests in the 4GL" section. For more information on encrypting MAC keys for secure audit archiving, see the sections on developing custom audit archiving tools in Chapter 3, " Auditing."